Integrating the Library with Frameworks

The default UI provided with the library package was created using web components and it is used on all our sample HTML templates. However, the ChartIQ library can also be integrated with a range of different JavaScript frameworks.

There are several reasons why you might want to use the ChartIQ library with a framework:

You want a completely different look and feel from what the web components provide
You're integrating the charts into an existing application that is already implemented in a framework
You prefer a deep integration with a UI framework for more control over the individual components

Whatever your reason, integration with a framework is straightforward if you follow the best practices that are outlined in this tutorial.

Framework-specific charting applications are complete offerings that come with a full-featured UI ready to run on Angular, React, and Vue without needing to write any code. They leverage our web components and can be requested as an add-on to the core API package. Of course, all the code will be provided, so it is also possible to customize the applications so long as you have adequate web component development knowledge in addition to knowledge of the framework you will be using.

Our integration philosophy for our charting applications is to create reusable custom elements that can be plugged into any framework. This allows developers to produce the same look and feel regardless of architecture. To this end, we have created a series of web components to leverage all key API calls in an advanced UI. Custom elements allow you to extend HTML and define your own tags. They are the linchpin in web component specifications. They give developers the ability to define their own HTML elements. When coupled with a shadow DOM, custom elements work in any application, including frameworks, which makes them the perfect reusable building block.

More details on our web component implementation can be found in the Web Component Interface tutorial.

License requirements

All starter kits require a valid charting library package. See the particular starter kits for exact version requirements.

As of Version 9.0.0, you can configure how you import the keyfile that contains your license key so that you can extend your license without recompiling and redeploying your app. See "Hot swapping" the keyfile for instructions.

Best practices

Utilize callbacks appropriately to ensure the UI is in sync with the chart.

One of the most common issues when integrating the library with a framework is that the UI and the chart get out of sync after the user changes something. Many frameworks rely on digest loops that often only run under certain circumstances. If you run into this problem, read the documentation for your framework and identify what you can do to manually trigger a digest loop to force the UI to update. Listening for the library engine events, callbacks, and property changes are a perfect places to trigger a digest loop.
Follow the best practices for your framework.

This is sometimes referred to as programming "idiomatically". Once you choose a framework, you should commit to doing things their way. This will make your code more consistent and readable, much easier to debug, and ensure that you are getting the most out of your framework. For example, different data flow differs among frameworks. Frameworks also often have their own way of looping through collections of data. Whatever way is considered to be most in line with your framework is the way you should do it. Treat the library as a pure JavaScript library (not a UI library) and make calls when needed.
Utilize any debugging tools that are specifically for your framework.

Most popular frameworks have debugging tools made specifically for that framework. Some examples of these are Chrome extensions for React, Vue.js, and Angular. Consider adding these tools to your development environment to make it easier to view changes within your framework components.

What to know when linting, minifying, or packaging the library

If you are:

running the code through a JS linter, typescript linter, and the like
minifying chartiq.js
packaging the library into a larger solution using module bundlers such as webpack

you might experience errors or warnings, depending on your settings.

Here are some suggestions you can try, one at a time, if you do have issues:

The library uses module imports so the CIQ namespace is not available in global and cannot be used with "classic" script tags directly. In order to use the library with classic script tags, it needs to be compiled and bundled. A sample bundling option using webpack is provided in the webpack-bundling-for-classic-script-tags folder.
Override the default compiler settings:

Set :
```
"allowJs": true
"checkJs": false
```
Instruct your linter to ignore the library files:

Update your tslint config to ignore imported libraries. Look for a tslint.json file in your project or for a tslint config entry in the package.json file and adjust it so it will not lint anything in the charting library folder, which should look something like this:
```
{
	"extends": "tslint:latest",
	"linterOptions": {
		"exclude": [
			"chartiq-library-folder/*.js"
		]
	}
}
```
Our new obfuscation process is very sensitive to file modification. Do not modify or even remove spaces between characters in chartiq.js as this may cause syntax errors.

For example, if spaces are removed form this line:
```
case 33: x8m = R8m[1] + +R8m[0]; break;
```
It will become:
```
case33: x8m=R8m[1]++R8m[0]; break;
```
The resulting ++ causes a JavaScript syntax error.

Integrating the Library with Frameworks

License requirements

Best practices

What to know when linting, minifying, or packaging the library

Next steps